feat(events): canonical per-family payload on event routes beside the native envelope (#466) - #545

Fixes #466.

What

Every event route now receives a canonical, per-family canonical.payload beside the raw native envelope. AgentEventRouteProps<E> (and AgentEventCanonicalIdentity<E>) take the route's family as a type parameter and narrow payload to that family's fields; the bare AgentEventRouteProps keeps working with every field optional.

• Shape. Each field is { value, nativeKey } | undefined (AgentEventPayloadField<T>): the decoded value beside the host key it was read from, so a route can tell mapped from missing and still name the host's spelling. A field the host did not send is absent — never defaulted, never inferred from another key. Two readings go beyond "read the key": Cursor tool_output (a JSON string) is parsed into toolResponse and kept as the string when it is not valid JSON; Cursor loop_count becomes the reentry boolean (> 0). Claude/Codex stop_hook_active is reentry as-is.
• Admission rule. A field is on a family's payload only when ≥ 2 of the hosts that support the family report it (single-host families — Claude's task/*, file/change, …, Cursor's workspace/open — carry their defining fields). The rule is enforced by a test, which is how model ended up on the nine three-host families only (Claude sends it on SessionStart alone).
• native is untouched, idempotencyKey still hashes only { event, native, target } (payload is derived, so a mapping change never re-identifies an event), and permissionDecision projection from fix(events): tool/before pass-through projects no decision instead of allow (#461) #481 is not touched.

Where the table lives

• packages/agent-bundle/src/routes/events.ts — the one table: agentEventPayloadFieldTypes / agentEventPayloadFieldKinds (vocabulary + JSON shape), agentEventPayloadFields (per family, drives AgentEventPayload<E>), agentEventPayloadNativeKeys (per host × family → { nativeKey, decode? }). All exported from agent-bundle, agent-bundle/routes, agent-bundle/api.
• packages/agent-bundle/src/events/payload.ts — projectEventPayload(event, native, target), called from createCanonicalEventProps, which every surface goes through (standalone hook wrapper, shared runtime IPC, agent-bundle/test, Workbench replay). Unknown/portable/composite-unresolved hosts get {}.
• Each pinned capability table mirrors its host's mapping under hooks.eventRoutes.<event>.payload (claude-2.1.250.json, codex-0.147.0.json, cursor-2026-08-28.json) so the generated events reference renders the matrix; tests/event-payload.test.ts holds the JSON equal to the runtime table field for field, and rejects a payload on an unsupported row or a missing one on a supported row.
• Generated docs: website/plugins/generated-reference.ts adds a "Canonical payload fields" section (one field × host table per family) to reference/events.

Payload shape per family (field × host → native key; — = host never sends it)

Evidence: the live captures under fixtures/host-lineage/ (Claude 2.1.259, Codex 0.147.0, Cursor 3.18.25), the pinned Codex input schemas, validateNativeEventEnvelope, the Claude hooks reference ("Common input fields": model reaches SessionStart only; permission_mode "not all events"; agent_id/agent_type on every hook inside a subagent), and https://cursor.com/docs/hooks (cwd on tool events only; no permission mode; conversation_id). Cursor subagentStop.subagent_id is undocumented but observed on 3.18.25 and mapped if present.

Deliberately not modelled (single host, or unit unpinned): Cursor attachments, generation_id, workspace_roots outside workspace/open, duration/duration_ms (Cursor's duration unit is not pinned), status, parent_conversation_id, task/summary; Claude prompt_id, effort, background_tasks, session_crons, compact_summary, custom_instructions, permission_decision(_reason); Codex turn_id. All stay on native. Turn/generation ids are already request.lineage.generation.

Tests

• tests/event-payload.test.ts (unit): projects every event in the three live captures through the real table and checks each payload field back against the envelope (nativeKey matches the mapping and the key exists; identity decodes deep-equal the native value; nothing mapped-and-present is dropped); the issue's acceptance — tool/before reading only toolName/toolInput under the Claude, Codex, and Cursor captures; stop reentry true for stop_hook_active: true and Cursor loop_count: 1; Cursor tool_output parsed / kept as string; Cursor session/start has no source/cwd/permissionMode, transcript_path: null stays null, wrong shapes are dropped, portable/plugin/unsupported-family → {}; idempotency key unchanged by the payload; JSON mirror ≡ runtime table; the ≥ 2-hosts admission rule.
• tests/route-register-typegen.test.ts (typegen, against the published declarations): a route typed AgentEventRouteProps<'tool/after'> registers RegisteredRouteInput<'event:tool/after'>['canonical'] as AgentEventCanonicalIdentity<'tool/after'> and its payload as AgentEventPayload<'tool/after'>; payload.reentry on it is a compile error; passing a stop input to it is a compile error; createEventRouteInput narrows.
• tests/generated-route-server.test.ts: the real compiled hook wrapper → shared runtime → route path on Claude and Cursor now asserts the route saw toolName@tool_name and the parsed toolResponse (tool_response object on Claude, tool_output JSON string parsed on Cursor) while native kept the raw string.
• Route-unit: examples/worktree-proximity (10), examples/rsc-agent-runtime (3), examples/host-test (7) via the new createEventRouteInput; repo route-unit pool 58/58; projection pool 158/158; Workbench lifecycle client/model/page tests updated (payload rows + strict schema).

Consumers

• agent-bundle/test gains createEventRouteInput(event, native, { host, nativeEvent?, hostContractRevision?, validate? }) — validates per host/event like the wrapper and returns the typed { canonical, native } the harness takes. Hand-built canonical objects must now include payload (the only breaking-ish edge; all in-repo callers migrated to the helper).
• Examples: worktree-proximity (src/event-support.ts now takes AgentEventPayload — carriedChild, extractIntent, actorForWorktree; the five routes are typed to their families and no longer take native), rsc-agent-runtime (src/events/tool/after.tsx reads cwd/sessionId/toolName/toolInput from the payload; only editedPath — Claude file_path vs Codex apply_patch header — stays host-specific in hook/normalize.ts, still shared with the hand-rolled hook CLI). host-test keeps reading native on purpose: it is the probe that records the raw envelope, and its captures now include canonical.payload automatically. hooks-and-scripts has no event route (config hooks only; that surface is feat(hooks): export HookHandler / HookEvent / HookResult — the typed config hook handler contract #533's).
• Workbench: the Lifecycles evidence panel lists the mapped payload (field → value · nativeKey) under "Canonical payload"; the strict replay schema admits exactly { nativeKey, value } per field.

cargo-hauler sites that become deletable once pinned (not edited here)

src/lib/event-support.ts @ current main:

• :54-67 beforeShellEventFrom → canonical.payload.{cwd,sessionId,toolInput,toolName,toolUseId}?.value
• :69-77 toolResponseFrom (object vs Cursor JSON string) → canonical.payload.toolResponse?.value
• :79-85 afterShellEventFrom → same as above plus toolResponse
• :87-96 stopHookActiveFrom (stop_hook_active vs loop_count) → canonical.payload.reentry?.value
• :98-105 stopHoldEventFrom → canonical.payload.{sessionId,reentry}
• :16-33 nativeString / nativeRecord / parseJsonRecord helpers → unused after the above
• :45-52 hookContextFrom stays (it is provenance, already on canonical.provenance), and :124 decisionValue stays, as the issue predicted.

movie-library (/fast/projects/agent-plugins/movie-library, 15e9459): its only event route src/events/session/start.tsx reads neither native nor canonical, so nothing becomes deletable there.

Coordination

• feat(hooks): export HookHandler / HookEvent / HookResult — the typed config hook handler contract #533 (HookHandler / HookEvent / HookResult, Typed hook handler contract: export HookHandler<'sessionStart'> / HookEvent / HookResult instead of restating the interface in docs and every example #488) landed first (0554f01e8), so this PR was rebased over it. Its table (adapters/hook-handler.ts: hookEventFields, HookEventPayloads) is the wrapper-decoded payload of the six plain-hook events — plain values, required/optional per field, plus wrapper-only fields (effort, hookEventName, promptId, turnId); this PR's table (routes/events.ts) is the provenance-carrying payload of all 22 event-route families, admitted by the ≥2-hosts rule. Importing one into the other would have changed feat(hooks): export HookHandler / HookEvent / HookResult — the typed config hook handler contract #533's public types at merge time, so the two are held to one vocabulary instead: tests/event-payload.test.ts now asserts every field hookEventFields[event].required guarantees is admitted for the matching family under the same name (stopHookActive → reentry is the one renaming), and the changeset says so. Folding HookEventPayloads onto agentEventPayloadFields is a follow-up, not done here.
• chore/claude-capability-2-1-260 landed as chore(claude): re-pin the Claude Code capability contract 2.1.250 → 2.1.260 #542 (fe8b026f2, claude-2.1.250.json → claude-2.1.260.json), so this PR was rebased over it: the payload mirror was regenerated onto the 2.1.260 table (hooks.eventRoutes.<event>.payload, 22 rows), and the two families the re-pin admits — model-switch/before (PreModelSwitch) and model-switch/after (PostModelSwitch), Claude-only — are added to canonicalAgentEvents in routes/events.ts, to agentEventPayloadFields with fromModel / toModel / requestedModel (string | null) / source beside the session fields, and to the Claude row of agentEventPayloadNativeKeys. Their cache_ttl, context_tokens, estimated_cache_write_usd, pricing, and prompt_cache_warm stay in native. Tested against tests/fixtures/events/claude-{pre,post}-model-switch.json.
• Rebase conflicts resolved along the way (all import-list or fixture-shape merges, no behaviour change): examples/worktree-proximity/src/events/session/start.tsx (feat(notices): address a notice to a lineage conversation or root (#458) #539 ROOT_ACTOR_PREFIX beside this PR's nonEmpty), examples/worktree-proximity/tests/route-unit/routes.test.ts (feat(notices): publisher-scoped notices.published() with per-notice state (#460) #541 agent/runAgentRequest beside createEventRouteInput), routes/public.ts (feat(runtime): expose the terminal capability to routes and scripts as request.terminal (#511) #534 AgentTerminal import; the canonicalAgentEvents definition moved to routes/events.ts now carries the model-switch/* entries), src/index.ts + routes/index.ts (feat(routes): let a route declare its render budget with config.render.maxElapsedMs (#454) #526 MAX_ROUTE_RENDER_ELAPSED_MS beside the payload exports), and the Claude capability JSON rename.

Docs

website/docs/{en,zh}/guide/authoring/hooks.mdx (new "The canonical payload" section, route example typed to its family, createEventRouteInput), website/docs/{en,zh}/guide/development/testing.mdx, docs/entry-conventions.md (event-route contract row), examples/rsc-agent-runtime/README.md; generated reference/events gains the per-family matrix. pnpm docs:site:build passes (dead-link/anchor/parity).

Changeset

.changeset/466-canonical-event-payload.md — agent-bundle: minor. Opened as patch (the runtime, artifact, wrapper, and output contracts are unchanged; native is unchanged; a route typed with the bare AgentEventRouteProps compiles unchanged), then raised to minor on the reviewer's P1: payload is a required property of the public AgentEventCanonicalIdentity, so a downstream test or harness that constructs the identity by hand — every in-repo example did until this PR, and cargo-hauler's tests likely do — stops compiling until it adds one, which is consumer action under the pre-1.0 rule (minor = breaking). The fix on the consumer side is createEventRouteInput.

Checks

pnpm typecheck, pnpm lint clean; pnpm test:unit 3266/3266; pnpm test:route-unit 58/58; pnpm test:projection 158/158; integration subset (generated-route-server event tests, lifecycle-replay-dev-server, target-hook-contract, hook-playground-service, public-api, route-register-typegen, worktree-proximity-journeys) green; pnpm docs:site:build passes; the three examples' typecheck + route-unit suites pass.

Review status

• 6361fd7ce — Codex reviewed (2 threads). Both addressed in the follow-up commit: P1 changeset raised to minor (see Changeset above); P2 agentEventPayloadFields, agentEventPayloadFieldKinds, and agentEventPayloadNativeKeys are now deepFreezed (the family arrays share instances, so a push from a JS consumer would have altered every later projection), with a test asserting the tables are frozen through.
• Later heads (6971913e8, 4fd5bafbe, 798620e28, f7b1e8a60, 35bd89de1, bb7db6b29, and any gh pr update-branch merge commit after it) — no fresh review arrived on any of them; per the AGENTS.md quota fallback the last-reviewed head is 6361fd7ce. The unreviewed delta is: the two-thread fix, six rebases onto a fast-moving main (feat(test): mountTestState/withTestState — one mounted state across several renderRoute calls #525, ci: run required checks on merge_group for the merge queue #536, feat(notices): address a notice to a lineage conversation or root (#458) #539, feat(notices): publisher-scoped notices.published() with per-notice state (#460) #541, chore(claude): re-pin the Claude Code capability contract 2.1.250 → 2.1.260 #542, feat(hooks): export HookHandler / HookEvent / HookResult — the typed config hook handler contract #533, feat(runtime): expose the terminal capability to routes and scripts as request.terminal (#511) #534, feat(api): export the dev.runtime.provider protocol types, errors, store and registry contracts from agent-bundle/api #528, refactor(effect): run ordinary I/O of validators, services, eval, and post-build readers through FileSystem (phase 2, PR 1) #540, feat(routes): let a route declare its render budget with config.render.maxElapsedMs (#454) #526), the model-switch/* admission and the HookEvent overlap test described under Coordination, and the claude-2.1.260.json mirror. Merging on green CI via gh pr update-branch + gh pr merge --squash --auto (branch-protected main, strict: true, no --admin); any thread opened afterwards is answered in a follow-up PR.

No PR comments are posted from this task; review threads are answered by commits and recorded here.